<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Berkeley DB handles</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="program.html" title="Chapter 17.  Programmer Notes" />
    <link rel="prev" href="program_mt.html" title="Multithreaded applications" />
    <link rel="next" href="program_namespace.html" title="Name spaces" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Berkeley DB handles</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="program_mt.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 17.  Programmer Notes </th>
          <td width="20%" align="right"> <a accesskey="n" href="program_namespace.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="program_scope"></a>Berkeley DB handles</h2>
          </div>
        </div>
      </div>
      <p>
        The Berkeley DB library has a number of object handles. The
        following table lists those handles, their scope, and whether
        they are free-threaded (that is, whether multiple threads
        within a process can share them).
    </p>
      <div class="variablelist">
        <dl>
          <dt>
            <span class="term">
              <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
            </span>
          </dt>
          <dd>
            <p> 
                    The <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle, created by the <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a>
                    method, refers to a Berkeley DB database
                    environment — a collection of Berkeley DB
                    subsystems, log files and databases. <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handles
                    are free-threaded if the <a href="../api_reference/C/envopen.html#envopen_DB_THREAD" class="olink">DB_THREAD</a> flag is
                    specified to the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method when the
                    environment is opened. The handle should not be
                    closed while any other handle remains open that is
                    using it as a reference (for example, <a href="../api_reference/C/db.html" class="olink">DB</a>,
                    <a href="../api_reference/C/txn.html" class="olink">TXN</a>). Once either the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> or <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a>
                    methods are called, the handle may not be accessed
                    again, regardless of the method's return. 
                </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/txn.html" class="olink">TXN</a>
            </span>
          </dt>
          <dd>
            <p> 
                    The <a href="../api_reference/C/txn.html" class="olink">TXN</a> handle, created by the <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV-&gt;txn_begin()</a>
                    method, refers to a single transaction. The handle
                    is not free-threaded. Transactions may span
                    threads, but only serially, that is, the
                    application must serialize access to the <a href="../api_reference/C/txn.html" class="olink">TXN</a>
                    handles. In the case of nested transactions, since
                    all child transactions are part of the same parent
                    transaction, they must observe the same
                    constraints. That is, children may execute in
                    different threads only if each child executes
                    serially. 
                </p>
            <p> 
                    Once the <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN-&gt;abort()</a> or <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN-&gt;commit()</a> methods are
                    called, the handle may not be accessed again,
                    regardless of the method's return. In addition,
                    parent transactions may not issue any Berkeley DB
                    operations while they have active child
                    transactions (child transactions that have not yet
                    been committed or aborted) except for <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV-&gt;txn_begin()</a>,
                    <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN-&gt;abort()</a> and <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN-&gt;commit()</a>. 
                </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a>
            </span>
          </dt>
          <dd>
            <p> 
                    The <a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a> handle refers to a cursor into the
                    log files. The handle is not free-threaded. Once
                    the <a href="../api_reference/C/logcclose.html" class="olink">DB_LOGC-&gt;close()</a> method is called, the handle may
                    not be accessed again, regardless of the method's
                    return.
                </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a>
            </span>
          </dt>
          <dd>
            <p>
                    The <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> handle refers to an open file in the
                    shared memory buffer pool of the database
                    environment. The handle is not free-threaded. Once
                    the <a href="../api_reference/C/mempfclose.html" class="olink">DB_MPOOLFILE-&gt;close()</a> method is called, the handle may
                    not be accessed again, regardless of the method's
                    return. 
                </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/db.html" class="olink">DB</a>
            </span>
          </dt>
          <dd>
            <p> 
                    The <a href="../api_reference/C/db.html" class="olink">DB</a> handle, created by the <a href="../api_reference/C/dbcreate.html" class="olink">db_create()</a>
                    method, refers to a single Berkeley DB database,
                    which may or may not be part of a database
                    environment. <a href="../api_reference/C/db.html" class="olink">DB</a> handles are free-threaded if the
                    <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag is specified to the <a href="../api_reference/C/dbopen.html" class="olink">DB-&gt;open()</a>
                    method when the database is opened or if the
                    database environment in which the database is
                    opened is free-threaded. The handle should not be
                    closed while any other handle that refers to the
                    database is in use; for example, database handles
                    should be left open while cursor handles into the
                    database remain open, or transactions that include
                    operations on the database have not yet been
                    committed or aborted. Once the <a href="../api_reference/C/dbclose.html" class="olink">DB-&gt;close()</a>,
                    <a href="../api_reference/C/dbremove.html" class="olink">DB-&gt;remove()</a> or <a href="../api_reference/C/dbrename.html" class="olink">DB-&gt;rename()</a> methods are called, the
                    handle may not be accessed again, regardless of
                    the method's return. 
                </p>
          </dd>
          <dt>
            <span class="term">
              <a href="../api_reference/C/dbc.html" class="olink">DBC</a>
            </span>
          </dt>
          <dd>
            <p> 
                    The <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handle refers to a cursor into a
                    Berkeley DB database. The handle is not
                    free-threaded. Cursors may span threads, but only
                    serially, that is, the application must serialize
                    access to the <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handles. If the cursor is to
                    be used to perform operations on behalf of a
                    transaction, the cursor must be opened and closed
                    within the context of that single transaction.
                    Once <a href="../api_reference/C/dbcclose.html" class="olink">DBC-&gt;close()</a> has been called, the handle may
                    not be accessed again, regardless of the method's
                    return. 
                </p>
          </dd>
        </dl>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="program_mt.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="program.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="program_namespace.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Multithreaded applications </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Name spaces</td>
        </tr>
      </table>
    </div>
  </body>
</html>
